home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1996 March / EnigmA AMIGA RUN 05 (1996)(G.R. Edizioni)(IT)[!][issue 1996-03][Skylink CD IV].iso / earcd / comm2 / xstat115.lha / XStat.doc < prev    next >
Text File  |  1994-06-20  |  18KB  |  561 lines
  1. XStat V1.15 Documentation
  2. =========================
  3.  
  4. Program and documentation are (C) Copyright 1992-94 by Jürgen Weinelt.
  5.  
  6. IMPORT StdDisclaimer; (* in short: use it at your own risk *)
  7. XStat was carefully tested, but there's certainly plenty of room for bugs.
  8.  
  9. XStat V1.15 is Freeware, non-commercial distribution is o.k. as long as
  10. the following conditions are met:
  11.  
  12.   * Source, executable and documentation must be distributed together
  13.     (XStat.mod, XStat, XStat.data, XStat.doc, XStat.dok and Make),
  14.     and these files must be intact (you're not allowed to make changes).
  15.     You're NOT allowed to add files to the archive.
  16.  
  17.   * This program may be included on PD/freeware CDs if I am allowed
  18.     to order one of those CDs at 50% off the retail price (or cheaper :).
  19.     Of course a free copy of the CD would be even nicer...
  20.  
  21.     Exception: Fred Fish has UNCONDITIONAL permission to add this
  22.     program version to his library, no matter if he's distributing it
  23.     on floppy disk or on CD.
  24.  
  25.  
  26.  
  27. XStat requires AmigaOS V37 or later (that's 2.04 or later).
  28.  
  29.  
  30.  
  31. Purpose
  32. =======
  33. XStat extracts statistic information from the Xferstat file created
  34. by some UUCICOs (tested with the SWB and wUUCP variant). The most
  35. important information XStat offers to you is the phone cost for a
  36. certain number of connects.
  37.  
  38.  
  39.  
  40. Installation
  41. ============
  42. Copy the executable "XStat" to a directory in your "Path", preferably UUBIN:
  43.  
  44. There's only one more file that needs to be installed; it's called
  45. "XStat.data", and should be copied to your UULIB: directory.
  46.  
  47. You'll have to customize (edit) XStat.data to complete the installation.
  48.  
  49. The new V1.14 output formats and associated environment variables are
  50. documented in the file "FORMS.doc".
  51.  
  52.  
  53.  
  54. XStat.data
  55. ==========
  56. XStat.data contains the phone cost on a "per host" basis, in the following
  57. format:
  58.  
  59. XStat.data file header:
  60. -----------------------
  61. H XSTAT DATA
  62.  
  63. This header must be the first line of XStat.data
  64.  
  65. XStat.data comment line:
  66. ------------------------
  67. # any comments you wish to add to XStat.data
  68.  
  69. You may add comment lines anywhere in your XStat.data file, except before
  70. the file header.
  71.  
  72. XStat.data currency sign info:
  73. ------------------------------
  74. S <currency sign>
  75.  
  76. Tells XStat the currency sign for your country. This line must come before
  77. the first "N"-line. There can be only one "S"-line in your XStat.data file.
  78.  
  79. Examples:
  80.  
  81. # currency sign for the U.S.A.
  82. S $
  83.  
  84. # currency sign for Germany
  85. S DM
  86.  
  87. XStat.data host name info:
  88. --------------------------
  89. N <host name> <host name> ...
  90.  
  91. Starts a new connection cost data record. Must be followed by at least
  92. one "C"-line. <host name> should be the name of a host you're directly
  93. connected to, without any path or domain information.
  94.  
  95. Examples:
  96.  
  97. # my own newsfeed
  98. N imart
  99.  
  100. # my alternate newsfeed
  101. N cbmger
  102.  
  103. Since XStat V1.10, you can use the extended N-line syntax that allows
  104. you to specify multiple host names in a single N-line. All those hosts
  105. will have the same cost information.
  106.  
  107. Example:
  108.  
  109. # several hosts that have the same cost info's
  110. N cbmger brewak forge
  111.  
  112. Since XStat V1.11, you can use several consecutive N-lines.
  113.  
  114. Example:
  115.  
  116. # several hosts that have the same cost info's
  117. N cbmger
  118. N brewak forge
  119.  
  120. Maximum line length of a N-line is 100 characters.
  121.  
  122. Since XStat V1.11, you can also use the reserved host name ".default.".
  123. This cost info will be used for every connect for which the host name
  124. cannot be found in XStat.data.
  125.  
  126. Since XStat V1.12 you can also use the reserved host name ".illegal.".
  127. This name will be used by XStat whenever an XferStat line with empty
  128. host name is encountered; some UUCiCos write such lines when a
  129. connection is aborted prematurely.
  130.  
  131. XStat.data connection duration offset info:
  132. -------------------------------------------
  133. O <offset>
  134.  
  135. Tells XStat that the connection duration in the XferStat file is
  136. off by <offset> seconds. You can use this to compensate for the
  137. connection negotiation phase of the modems (which does not appear
  138. in the XferStat connection time). The option was only tested with
  139. positive offsets. The "O" line must come directly after the "N"
  140. line. There can be only one "O" line per host.
  141.  
  142. Example:
  143. N imart
  144. O 13
  145. C ...
  146.  
  147. Tells XStat that my modem will usually need 13 seconds to negotiate
  148. a connection with imart.
  149.  
  150. XStat.data connection time/cost info:
  151. -------------------------------------
  152. C <start time> <duration> <price>
  153.  
  154. Tells XStat that between <start time> and <start time of next C-line>
  155. a connection will cost <price> per <duration>. "C"-lines must follow
  156. a "N"-line. <duration> must be in seconds, <price> in the currency of
  157. your choice.
  158.  
  159. The first "C"-line must be for "SU-00:00:00"!
  160. (see exception at LOCAL/IGNORE below)
  161.  
  162. Example:
  163. N imart
  164. C SU-00:00:00 120 0.23
  165. C MO-08:00:00  60 0.23
  166. C MO-18:00:00 120 0.23
  167.  
  168. From Sunday 0:00:00 to Monday 7:59:59, a connection between my
  169. site and my newsfeed "imart" will cost 0.23DM/120sec.
  170.  
  171. Between Monday 8:00:00 and Monday 17:59:59, a connection between my site
  172. and my newsfeed "imart" will cost 0.23DM/60sec.
  173.  
  174. With this short example, the connection cost for the rest of the
  175. week (from Monday 18:00:00 to Saturday 23:59:59) would be 0.23DM/120sec.
  176.  
  177. Since Version 1.09 there's another possible C-line syntax... you
  178. can also use "C IGNORE" to tell XStat to ignore all connections from
  179. and to that particular host, or you can use "C LOCAL" to specify a
  180. local connection without connection costs (only the in/out bytes
  181. will be counted in this case). If you use "LOCAL" or "IGNORE", you
  182. may NOT use the normal C-line syntax for that host.
  183. "LOCAL" and "IGNORE" are mutually exclusive.
  184.  
  185.  
  186. Example:
  187. N imart
  188. C IGNORE
  189.  
  190. will cause all connects from/to imart to be ignored.
  191.  
  192.  
  193. Example:
  194. N imart
  195. C LOCAL
  196.  
  197. will cause all connects from/to imart to be counted with cost=0.
  198.  
  199.  
  200. Since Version 1.14, you can also use a unit duration of "0" seconds,
  201. which will instruct XStat to assume a "flat rate" for the
  202. corresponding connections (one single "unit" will be counted for
  203. those connections).
  204.  
  205. Example:
  206. N imart
  207. C SU-00:00:00   0 0.23
  208. C MO-08:00:00  60 0.23
  209. C MO-18:00:00 120 0.23
  210.  
  211. Connections between Sunday, 0:00 and Monday, 8:00 will cost one
  212. single unit, no matter how long they were.
  213.  
  214.  
  215. Full length example for XStat.data:
  216. -----------------------------------
  217.  
  218. - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut -
  219. H XSTAT DATA
  220. #==============================================================================
  221. # XStat connection cost data file
  222. #==============================================================================
  223. #
  224. #------------------------------------------------------------------------------
  225. # currency sign for Germany; S must come before first N
  226. #------------------------------------------------------------------------------
  227. S DM
  228. #
  229. #------------------------------------------------------------------------------
  230. # my own newsfeed, connection cost is 0.23/60sec (0.23/120sec night & weekend)
  231. #------------------------------------------------------------------------------
  232. N imart
  233. N .illegal.
  234. C SU-00:00:00 120 0.23
  235. C MO-08:00:00  60 0.23
  236. C MO-18:00:00 120 0.23
  237. C TU-08:00:00  60 0.23
  238. C TU-18:00:00 120 0.23
  239. C WE-08:00:00  60 0.23
  240. C WE-18:00:00 120 0.23
  241. C TH-08:00:00  60 0.23
  242. C TH-18:00:00 120 0.23
  243. C FR-08:00:00  60 0.23
  244. C FR-18:00:00 120 0.23
  245. #
  246. #------------------------------------------------------------------------------
  247. # cbmger, brewak, forge, default:
  248. # connection cost is 0.23/21sec (0.23/42sec night & weekend)
  249. #------------------------------------------------------------------------------
  250. N cbmger
  251. N brewak forge
  252. N .default.
  253. C SU-00:00:00  42 0.23
  254. C MO-08:00:00  21 0.23
  255. C MO-18:00:00  42 0.23
  256. C TU-08:00:00  21 0.23
  257. C TU-18:00:00  42 0.23
  258. C WE-08:00:00  21 0.23
  259. C WE-18:00:00  42 0.23
  260. C TH-08:00:00  21 0.23
  261. C TH-18:00:00  42 0.23
  262. C FR-08:00:00  21 0.23
  263. C FR-18:00:00  42 0.23
  264. #
  265. #------------------------------------------------------------------------------
  266. # modula, this is a local (e.g. null-modem) connection
  267. #------------------------------------------------------------------------------
  268. N modula
  269. C LOCAL
  270. #
  271. #------------------------------------------------------------------------------
  272. # walker, connects will be ignored
  273. #------------------------------------------------------------------------------
  274. N walker
  275. C IGNORE
  276. #
  277. - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut - cut -
  278.  
  279.  
  280.  
  281. Usage
  282. =====
  283. XStat [?] [DATA name] [FILE name] [V | VERBOSE] [FD | FROMDATE date]
  284.           [TD | TODATE date] [NI | NOINCOM] [NO | NOOUTGO]
  285.           [H | HOSTNAME name] [M | MONTH shortdate] [SE | STDERR]
  286.           [P | PREVIOUS numdays] [L | LAST numdays]
  287.  
  288. Alternate description:
  289.  
  290. XStat FILE/K,DATA/K,V=VERBOSE/S,M=MONTH/K,NI=NOINCOM/S,NO=NOOUTGO/S,
  291.       Q=QUIET/S,H=HOSTNAME/K,FD=FROMDATE/K,TD=TODATE/K,SE=STDERR/S,
  292.       P=PERIOD/N,L=LAST/N
  293.  
  294. You may also use the environment variable "XSTATARGS" to specify
  295. parameters. This is very useful if you're using XStat from the
  296. Workbench (XStat doesn't really support Workbench, that's why
  297. there's no icon for it).
  298.  
  299. ?
  300. -
  301. Displays a help message.
  302.  
  303. DATA name
  304. ---------
  305. Tells XStat to read its connection cost data from file <name>.
  306. <name> defaults to "UULIB:XStat.data".
  307.  
  308. FILE name
  309. ---------
  310. Tells XStat to extract the statistic information from file <name>.
  311. <name> defaults to "UUSPOOL:XferStat".
  312.  
  313. V | VERBOSE
  314. -----------
  315. Enables the "verbose" mode. When on, XStat displays short statistics
  316. for every connect found in the Xferstat file. Defaults to "off".
  317. Specify VERBOSE to turn verbose mode on.
  318.  
  319. WARNING! The VERBOSE option will be changed drastically soon (probably
  320. in the next release).
  321.  
  322. FD | FROMDATE date
  323. ------------------
  324. Tells XStat to ignore connects before <date>. <date> defaults to "01-JAN-78".
  325. You may use any valid AmigaDOS date string, including things like
  326. "TODAY" or "YESTERDAY". XStat will add a time string of "00:00:00" internally,
  327. you may not do this yourself. Be careful, if you're using Workbench 2.1 (which
  328. is [ought to be] currently available to registered developers only) you'll have
  329. to use your locale date specifications, for example "HEUTE" instead of "TODAY"
  330. if you're using the german locale.
  331. Please read the warnings for "PREVIOUS" and "LAST"!
  332.  
  333. TD | TODATE date
  334. ----------------
  335. Tells XStat to ignore connects after <date>. <date> defaults to current
  336. date/time. You may use any valid AmigaDOS date string, including things
  337. like "TODAY" or "YESTERDAY" (with the same 2.1/locale limitations as FD).
  338. XStat will add a time string of "23:59:59" internally, you may not do this
  339. yourself.
  340. Please read the warnings for "PREVIOUS" and "LAST"!
  341.  
  342. M | MONTH shortdate
  343. -------------------
  344. Tells XStat to ignore FD and TD, and to compute the statistics for the
  345. specified month instead. The month must be given in the format "MMM-YY",
  346. without specifying the day. Example: "MONTH JUN-92" will compute the stats
  347. for June 92. MONTH is inactive as default.
  348. Please read the warnings for "PREVIOUS" and "LAST"!
  349.  
  350. NI | NOINCOM
  351. ------------
  352. Tells XStat to suppress evaluation of incoming calls; defaults to off.
  353. Specify "NI" to suppress evaluation of incoming calls. Meaning of this
  354. switch was inverted before version 1.04.
  355.  
  356. NO | NOOUTGO
  357. ------------
  358. Tells XStat to suppress evaluation of outgoing calls; defaults to off.
  359. Specify "NO" to suppress evaluation of outgoing calls. Meaning of this
  360. switch was inverted before version 1.04.
  361.  
  362. Q | QUIET
  363. ---------
  364. Tells XStat to suppress non-fatal error messages; defaults to off.
  365. Specify QUIET to suppress non-fatal errors.
  366.  
  367. This is very handy for getting rid of those "(ignoring this one)" messages
  368. for failed connects.
  369.  
  370. H | HOSTNAME
  371. ------------
  372. Tells XStat to evaluate calls to host <name> only; defaults to all hosts.
  373. Starting with V1.06, if <name> contains any valid AmigaDos pattern,
  374. XStat will display subtotals for each host that matches these patterns.
  375.  
  376. Patterns are not case sensitive.
  377.  
  378. Example: XStat hostname (a|x)#?
  379.          will evaluate calls to all hosts that start with an "a" or "x",
  380.          and will display sub-totals for each of those hosts.
  381.  
  382. New feature in 1.15:
  383. If the hostname is a simple string (no AmigaDOS patterns in it), then
  384. XStat will just produce statistics for that hosts, NOT any "TOTAL"s.
  385.  
  386. SE | STDERR
  387. -----------
  388. Tells XStat to send all error messages to StdErr instead of StdOut.
  389. Then you can redirect the statistic output to a file using ">File",
  390. without redirecting the error messages to that file as well.
  391. Redirection defaults to off; specify STDERR to enable redirecting
  392. error messages to StdErr. StdErr is always the console window
  393. XStat was started from. The STDERR option was tested with the
  394. standard AmigaShell only. It *should* work with other shells, too.
  395.  
  396. P | PERIOD numdays
  397. ------------------
  398. Display the statistics for a certain period of time; the period
  399. is from "FROMDATE" to "FROMDATE+numdays".
  400.  
  401. WARNINGS:
  402. (1) this overrides both "MONTH" and "TODATE"
  403. (2) there's no sanity checking done on "numdays", you can cause
  404.     an internal overflow by specifying extremely large values
  405. (3) you're not allowed to specify "PERIOD" and "LAST" simultaneously
  406. (4) "numdays"=1 displays statistics for "FROMDATE" and the following day
  407.  
  408. L | LAST numdays
  409. ----------------
  410. Display the statistics for a certain period of time; the period
  411. is from "TODATE-numdays" to "TODATE".
  412.  
  413. WARNINGS:
  414. (1) this overrides both "MONTH" and "FROMDATE"
  415. (2) there's no sanity checking done on "numdays", you can cause
  416.     an internal underflow by specifying extremely large values
  417. (3) you're not allowed to specify "PERIOD" and "LAST" simultaneously
  418. (4) "numdays"=1 displays statistics for "TODATE" and the day before
  419.  
  420.  
  421.  
  422. XStat's output
  423. ==============
  424.  
  425. Example:
  426.  
  427. > (On 25-DEC-93) XStat last 30
  428. >
  429. > XStat 1.15
  430. > © Copyright 1992-94 by Jürgen Weinelt
  431. > XStat is Freeware - read the docs for details.
  432. >
  433. >
  434. >
  435. > TOTAL: Connection statistics for incoming calls.
  436. >
  437. [...]
  438. >
  439. >
  440. >
  441. > TOTAL: Connection statistics for outgoing calls.
  442. >
  443. > Transfer statistics from 25-Nov-93 18:24:07 to 25-Dez-93 18:24:07
  444. >
  445. > number of connects        54
  446. > local connects             0
  447. > ignored connects           0
  448. >
  449. > total online time       8112     seconds
  450. > total phone units         98     units
  451. > total phone cost          22.540 DM
  452. > average online time      151     seconds/connect
  453. > average phone units        1.815 units/connect
  454. > average phone cost         0.417 DM/connect
  455. >
  456. > total gross read    10491743     bytes
  457. > total gross send     1819008     bytes
  458. > total net read       8347777     bytes
  459. > total net send        106961     bytes
  460. > average gross read    194292     bytes/connect
  461. > average gross send     33686     bytes/connect
  462. > average net read      154589     bytes/connect
  463. > average net send        1981     bytes/connect
  464. >
  465. > average speed           1517     CPS (gross data transfer)
  466. > fastest connect         1653     CPS (gross data transfer)
  467. > average speed           1042     CPS (net data transfer)
  468. > fastest connect         1366     CPS (net data transfer)
  469. >
  470. > average cost               1.920 DM/MB (gross data transfer)
  471. > average cost               2.795 DM/MB (net data transfer)
  472.  
  473. Notes:
  474.  
  475. "gross" means, the figure includes the protocol overhead.
  476.  
  477. "net" means, the figure excludes the protocol overhead.
  478.  
  479.  
  480.  
  481. History
  482. =======
  483. V1.15   fixed FORMS.doc, fixed formatting bug, enhanced the "&HN" format,
  484.         added "WARN" returncode for empty statistics (no connects).
  485. V1.14   added output formats, connection time offset, flat rate feature
  486. V1.13   added "PREVIOUS" and "LAST", added date line to output
  487. V1.12   added ".illegal." feature
  488.         fixed a potential bug in the XferStat parsing code
  489. V1.11   added multiple N-line feature and ".default." host name to XStat.data
  490.           N-Line Syntax.
  491.         fixed a minor bug in the EOF handling of the Xferstat parser.
  492. V1.10   added multiple name feature to XStat.data N-Line syntax
  493.         fixed a small bug in the NI/NO feature
  494. V1.09   added LOCAL and IGNORE to XStat.data C-line syntax
  495. V1.08   added STDERR option, replaced "ø" with "av."
  496. V1.07   list of connection statistics was not sorted correctly. Fixed.
  497. V1.06   extended "hostname" to include pattern matching and "per host" feature
  498. V1.05   added "per host" statistics
  499. V1.04   fixed a bug (problem with locale), switched to dos.library "ReadArgs()"
  500. V1.03   added monthly statistics.
  501. V1.02   added peak brutto/netto cps rating.
  502. V1.01   XStat used to guru when brutto or netto xfer was 0 bytes. Fixed.
  503. V1.00   initial release.
  504.  
  505. V0.9x   several test/beta versions, limited circulation
  506.  
  507.  
  508.  
  509. Known problems/bugs
  510. ===================
  511. The MONTH option yields inaccurate results. This is not a bug in XStat.
  512. The date conversion routines from dos.library are broken; C= will fix this
  513. in the release version of [whatever comes after Kickstart 3.0].
  514.  
  515. The online time is not very accurate. That's because the connection start
  516. time seems to state the time the modem says "CONNECT", not the real
  517. start time of the (phone line) connection. This can be improved by using
  518. the new 1.14 "connection time offset" feature.
  519.  
  520.  
  521.  
  522. If you have questions or bug reports...
  523. =======================================
  524. You can contact me by eMail:
  525.  
  526.    jow@rz.uni-wuerzburg.de (preferred)
  527.    jow@hcast.franken.de
  528.    jow@hcast.adsp.sub.org (avoid if possible)
  529.  
  530. Or through the snail mail:
  531.  
  532.    Jürgen Weinelt
  533.    Franz-Ludwig-Strasse 10
  534.    D-97072 Wuerzburg
  535.    Germany
  536.  
  537. You might also try posting to alt.sys.amiga.uucp.
  538.  
  539.  
  540.  
  541. Thanks
  542. ======
  543. The following people contributed suggestions and bug reports:
  544.  
  545.          Christian Balzer
  546.                Kai Bolay
  547.           Christof Damian
  548.   Hartmut "Essich" Goebel
  549.           Tommy V. Hansen
  550.              Tapio Heiskanen
  551.   Michael-Wolfgang Hohmann
  552.            Alfredo Jahn V
  553.    Andrew "Charly" Kopp
  554.               Erik Kunze
  555.    Matthias "Tron" Scheler
  556.  Henning "Barnard" Schmiedehausen
  557.        Kai "wusel" Siering
  558.       Peter "Peti" Simons
  559.  
  560. Thank you all.
  561.